Inside Macintosh: Sound
| Previous | Chapter contents | Chapter top | Section top | Next |
If you use a high-level Sound Manager routine to play sounds, you might be able to let the Sound Manager internally allocate a sound channel. However, to use low-level sound commands or to take full advantage of the Sound Manager's high-level routines, you must allocate your own sound channels. The SndNewChannel function allows your application to allocate a new sound channel, and the SndDisposeChannel function allows your application to dispose of it.
You can use the SndNewChannel function to allocate a new sound channel.
FUNCTION SndNewChannel (VAR chan: SndChannelPtr; synth: Integer;
init: LongInt; userRoutine: ProcPtr):
OSErr;
The SndNewChannel function internally allocates memory to store a queue of sound commands. If you pass a pointer to NIL as the chan parameter, the function also allocates a sound channel record in your application's heap and returns a pointer to that record. If you do not pass a pointer to NIL as the chan parameter, then that parameter must contain a pointer to a sound channel record.
If you pass a pointer to NIL as the chan parameter, then the amount of memory the SndNewChannel function allocates to store the sound commands is enough to store 128 sound commands. However, if you pass a pointer to the sound channel record rather than a pointer to NIL , the amount of memory allocated is determined by the qLength field of the sound channel record. Thus, if you wish to control the size of the sound queue, you must allocate your own sound channel record. Regardless of whether you allocate your own sound channel record, the Sound Manager allocates memory for the sound command queue internally.
The synth parameter specifies the sound data type you intend to play on this channel. You can use these constants to specify the data type:
CONST
squareWaveSynth = 1; {square-wave data}
waveTableSynth = 3; {wave-table data}
sampledSynth = 5; {sampled-sound data}
In Sound Manager versions earlier than version 3.0, only one data type can be produced at any one time. As a result, SndNewChannel may fail if you attempt to open a channel specifying a data type other than the one currently being played.
To specify a sound output device other than the current sound output device, pass the value kUseOptionalOutputDevice in the synth parameter and the signature of the desired sound output device component in the init parameter.
CONST
kUseOptionalOutputDevice = -1;
The ability to redirect output away from the current sound output device is intended for use by specialized applications that need to use a specific sound output device. In general, your application should always send sound to the current sound output device selected by the user.
Because the SndNewChannel function allocates memory, you should not call it at interrupt time.
For an example of a routine that uses the SndNewChannel function, see Listing 1-11 .
For information on the format of a callback procedure, see "Callback Procedures" .
If you allocate a sound channel by calling the SndNewChannel function, you must release the memory it occupies by calling the SndDisposeChannel function.
FUNCTION SndDisposeChannel (chan: SndChannelPtr;
quietNow: Boolean): OSErr;
The SndDisposeChannel function disposes of the queue of sound commands associated with the sound channel specified in the chan parameter. If your application created its own sound channel record in memory or installed a sound as a voice in a channel, the Sound Manager does not dispose of that memory. The Sound Manager also does not release memory associated with a sound resource that you have played on a channel. You might use the userInfo field of the sound channel record to store the address of a sound handle you wish to release before disposing of the sound channel itself.
The SndDisposeChannel function can dispose of a channel immediately or wait until the queued commands are processed. If quietNow is set to TRUE , a flushCmd command and then a quietCmd command are sent to the channel bypassing the command queue. This removes all commands, stops any sound in progress, and closes the channel. If quietNow is set to FALSE , then the Sound Manager issues a quietCmd command only; it does not bypass the command queue, and it waits until the quietCmd command is processed before disposing of the channel.
| Previous | Chapter contents | Chapter top | Section top | Next |